# Creating a new Custom Field

This endpoint returns structured Custom Field objects.
As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array
and will be indexed by ID in the `custom_fields` top-level JSON key.
Please see our [Response Format](#section/Response-Format) section for more information.

Endpoint: POST /custom_fields
Version: 1.0.0

## Query parameters:

  - `include` (string)
    Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`.
- `choices` (CustomFieldChoice) - Includes the ID of a Custom Field's choices.
- `creator` (User) - Includes the ID of a Custom Field's creator.
- `custom_field_set` (CustomFieldSet) - Includes the ID of the Custom Field Set that a field belongs to.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.

## Request fields (application/json):

  - `custom_field` (object)

  - `custom_field.name` (string, required)
    The name of the new field.

  - `custom_field.value_type` (string)
    The format of the [custom field's value](/tag/Custom-Field-Values):
| Value Type           | Format                                   | Sample         |
| -------------------- |:----------------------------------------:| --------------:|
| `string`             | `<text_string>`                          |        `"foo"` |
| `date`               | `<ISO_8601 Date Format>`                 | `"2014-02-25"` |
| `number`             | `<integer_value>`                        |           `13` |
| `currency`           | `[<int_value_in_cents>, <currency_code>]`| `[998, "USD"]` |
| `single` and `multi` | `[<choice_ids>]`                         |    `[1, 2, 4]` |

This is set to `string` by default.

  - `custom_field.default_text` (string)
    The message in an empty custom field, before a `string`, `date`, `number`, or `currency`  value is entered in.
This only appears in the UI.

  - `custom_field.unique_constraint` (boolean)
    A boolean setting that requires a custom field value to be unique across Estimates, Projects, Groups,
Resources, Tasks, or Users.

This is set to `false` by default.

  - `custom_field.choices` (array)
    The list of [choices](/tag/Custom-Field-Choices) a user can select from
for a custom field's value(s). A choice has two attributes, a `label` and an `ID`. Different choices can have the
same `label`, but every choice will have a unique `ID`.

For example, a request:

```
custom_field_choices: {
  ....
  choices: [
    { "label": "Choice A" },
    { "label": "Choice B" },
    { "label": "Choice B" },
    { "label": "Choice B" }
  ]
  ....
}

Will have a response like:

```
custom_field_choices: {
  ....
  choices: [
    { "label": "Choice A", "id": "180291" },
    { "label": "Choice B", "id": "180301" },
    { "label": "Choice B", "id": "180311" },
    { "label": "Choice B", "id": "180321" }
  ]
  ....
}
```

Choices in the UI appear in the same order as listed in the array.

Note that the 2nd, 3rd, and 4th choices all have the same label, but different IDs.

  - `custom_field.choices.label` (string)
    You can think of a label as the actual value a user can select for the custom field.

*Note:* Different choices can have the same `label`.

  - `custom_field.custom_field_set_id` (integer)
    The ID of the [Custom Field Set](/tag/Custom-Field-Sets) that the field belongs to.
When a set ID is not specified, the field is added to a Project set titled 'Default Project Set'.
This means it becomes a Project field.

  - `custom_field.write_access` (string)
    The permission level required for a user to create, update, or delete a custom field's value.

  - `custom_field.read_access` (string)
    The `read_access` [permission setting on each custom field](https://mavenlink.zendesk.com/hc/en-us/articles/202924760#see)
determines the minimum permission needed to view a custom field and its value.
* `Workspace` (Project), `Resource`, and `Story` (Task) custom fields are project-specific objects,
so their minimum permissions are set at the [project level](https://mavenlink.zendesk.com/hc/en-us/articles/115002779293-Project-Permissions):
  - `project_collaboration` (default)
  - `time_logging`
  - `financial`
  - `project_admin`

Most account-level permissions supercede project-level permissions. Therefore, Account Administrators are able to view
all Project, Resource, and Task custom fields and values across the account, regardless of project participation or
`read_access` settings.
* `Estimate`, `WorkspaceGroup` (Group), and `User` custom fields are account-wide objects, so their minimum permissions
are set at the [account level](https://mavenlink.zendesk.com/hc/en-us/articles/203041364):
  - `account_collaboration`
  - `project_creator`
  - `project_lead`
  - `reports_viewer`
  - `reports_viewer_with_cost`
  - `account_admin` (default).

## Response 200 fields (application/json):

  - `count` (integer)

  - `meta` (object)

  - `meta.count` (integer)

  - `meta.page_count` (integer)

  - `meta.page_number` (integer)

  - `meta.page_size` (integer)

  - `results` (array)

  - `results.key` (string)

  - `results.id` (string)

## Response 400 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 403 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 404 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 422 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.type` (string)

  - `errors.message` (string)